home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3 / SLGetPrinterSettings.z / SLGetPrinterSettings
Encoding:
Text File  |  1998-10-30  |  19.3 KB  |  331 lines
  1.  
  2.  
  3.  
  4. SSSSLLLLGGGGeeeettttPPPPrrrriiiinnnntttteeeerrrrSSSSeeeettttttttiiiinnnnggggssss((((3333))))          IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo           SSSSLLLLGGGGeeeettttPPPPrrrriiiinnnntttteeeerrrrSSSSeeeettttttttiiiinnnnggggssss((((3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      SLGetPrinterSettings, SLSysVGetSpoolerOptions, SLSysVGetPrinterOptions,
  10.      SLSysVSaveSpoolerOptions, SLSysVSavePrinterOptions - option management
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssppppoooooooollll....hhhh>>>>
  14.  
  15.      iiiinnnntttt SSSSLLLLGGGGeeeettttPPPPrrrriiiinnnntttteeeerrrrSSSSeeeettttttttiiiinnnnggggssss((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****pppprrrriiiinnnntttteeeerrrr,,,,
  16.                               SSSSLLLLSSSSeeeettttttttiiiinnnnggggssssSSSSttttrrrruuuucccctttt ********sssseeeettttttttiiiinnnnggggsssspppp))));;;;
  17.  
  18.      iiiinnnntttt SSSSLLLLSSSSyyyyssssVVVVGGGGeeeettttSSSSppppoooooooolllleeeerrrrOOOOppppttttiiiioooonnnnssss((((SSSSLLLLSSSSyyyyssssVVVVSSSSppppoooooooolllleeeerrrrOOOOppppttttiiiioooonnnnssssSSSSttttrrrruuuucccctttt
  19.                                  ********ssssppppoooooooolllleeeerrrr____ooooppppttttsssspppp))));;;;
  20.  
  21.      iiiinnnntttt SSSSLLLLSSSSyyyyssssVVVVGGGGeeeettttPPPPrrrriiiinnnntttteeeerrrrOOOOppppttttiiiioooonnnnssss((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****pppprrrriiiinnnntttteeeerrrr,,,,
  22.                                  cccchhhhaaaarrrr ********pppprrrriiiinnnntttteeeerrrr____ooooppppttttsssspppp))));;;;
  23.  
  24.      iiiinnnntttt SSSSLLLLSSSSyyyyssssVVVVSSSSaaaavvvveeeeSSSSppppoooooooolllleeeerrrrOOOOppppttttiiiioooonnnnssss((((SSSSLLLLSSSSyyyyssssVVVVSSSSppppoooooooolllleeeerrrrOOOOppppttttiiiioooonnnnssssSSSSttttrrrruuuucccctttt
  25.                                   ****ssssppppoooooooolllleeeerrrr____ooooppppttttssss))));;;;
  26.  
  27.      iiiinnnntttt SSSSLLLLSSSSyyyyssssVVVVSSSSaaaavvvveeeePPPPrrrriiiinnnntttteeeerrrrOOOOppppttttiiiioooonnnnssss((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****pppprrrriiiinnnntttteeeerrrr,,,,
  28.                                   cccchhhhaaaarrrr ****pppprrrriiiinnnntttteeeerrrr____ooooppppttttssss,,,,
  29.                                   iiiinnnntttt llllooooccccaaaattttiiiioooonnnn))));;;;
  30.  
  31. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  32.      The spooling system and the printer provide many options to customize
  33.      their behavior to the needs of the user. The Silicon Graphics printing
  34.      environment permits applications to save and retrieve these printing
  35.      options.  For example, a user can select duplex printing for a particular
  36.      printer and save this setting. From then on, whenever a print job is sent
  37.      to that printer it will be printed in duplex mode. This option management
  38.      is provided by the _l_i_b_s_p_o_o_l functions _S_L_G_e_t_P_r_i_n_t_e_r_S_e_t_t_i_n_g_s,
  39.      _S_L_S_y_s_V_G_e_t_S_p_o_o_l_e_r_O_p_t_i_o_n_s, _S_L_S_y_s_V_G_e_t_P_r_i_n_t_e_r_O_p_t_i_o_n_s,
  40.      _S_L_S_y_s_V_S_a_v_e_S_p_o_o_l_e_r_O_p_t_i_o_n_s and _S_L_S_y_s_V_S_a_v_e_P_r_i_n_t_e_r_O_p_t_i_o_n_s.
  41.  
  42.      Currently, option management is supported only under the System V
  43.      spooling system. Under the System V spooler the spooler options are the
  44.      _l_p(_1) command switches ----cccc, ----mmmm, ----wwww, ----ssss and ----tttt. Refer to the _l_p man page
  45.      for an explanation of these switches. Spooler options are maintained on a
  46.      per user basis. For example, a banner page title (-t) is saved for a
  47.      single user. That title will be used for all print jobs submitted by that
  48.      user to any printer.  Printer specific options are considered to be those
  49.      that would be specified using the _l_p command line switch ----oooo. Though there
  50.      are often numerous printer specific options, the _l_i_b_s_p_o_o_l option
  51.      management functions treat them together as a single whitespace separated
  52.      string of options. Printer options are maintained on a per user, per
  53.      printer basis. This means that a user can save the option to suppress the
  54.      printing of the banner for a specific printer without that settings
  55.      affecting any other user or printer.
  56.  
  57.      Note that an application must utilize the _l_i_b_s_p_o_o_l functions detailed
  58.      here to participate in spooler and printer option management. For
  59.      example, if an application submits a print job using _S_L_S_u_b_m_i_t_J_o_b, it is
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. SSSSLLLLGGGGeeeettttPPPPrrrriiiinnnntttteeeerrrrSSSSeeeettttttttiiiinnnnggggssss((((3333))))          IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo           SSSSLLLLGGGGeeeettttPPPPrrrriiiinnnntttteeeerrrrSSSSeeeettttttttiiiinnnnggggssss((((3333))))
  71.  
  72.  
  73.  
  74.      the application's responsibility to use the option management functions
  75.      to determine what option settings should be specified for the print job.
  76.      The _P_r_i_n_t_P_a_n_e_l and _l_p programs utilize the _l_i_b_s_p_o_o_l option management
  77.      facilities.  In order to provide a consistent printing environment, it is
  78.      strongly suggested that application developers utilize the _l_i_b_s_p_o_o_l
  79.      option management functions. The goal is to remember user printing
  80.      preferences across applications.
  81.  
  82.      While spooler and printer options are typically handled in a spooling
  83.      system dependent manner, the _S_L_G_e_t_P_r_i_n_t_e_r_S_e_t_t_i_n_g_s reads these settings
  84.      into the spooling system independent option structure _S_L_S_e_t_t_i_n_g_s_S_t_r_u_c_t.
  85.      This function reads both the spooler and printer options. As contained in
  86.      the _S_L_S_e_t_t_i_n_g_s_S_t_r_u_c_t, the settings can be passed as parameters to the
  87.      _l_i_b_s_p_o_o_l print job submittal functions (e.g. _S_L_S_u_b_m_i_t_J_o_b).  By using the
  88.      _S_L_G_e_t_P_r_i_n_t_e_r_S_e_t_t_i_n_g_s function, an application can submit a print job
  89.      using options that the submitter has previously saved using SGI's
  90.      printing tools.  Thus, the print job will be customized to match the
  91.      preferences of the user.
  92.  
  93.      The _S_L_S_y_s_V_G_e_t_S_p_o_o_l_e_r_O_p_t_i_o_n_s and _S_L_S_y_s_V_S_a_v_e_S_p_o_o_l_e_r_O_p_t_i_o_n_s functions read
  94.      and write System V spooling system options, respectively. These are
  95.      System V spooling system specific functions and an error indication will
  96.      be returned if these functions are called when the System V spooler is
  97.      not the current spooling system. Spooling system specific options are
  98.      saved in the caller's home directory under the name ._g_l_p_r_c.  This file
  99.      contains a single line of spooler specific option switches. The switches
  100.      are the same as the spooler specific command line switches used by the _l_p
  101.      program with the exception that the ----dddd, and ----nnnn switches are never saved.
  102.      These functions pass the spooler options in the
  103.      _S_L_S_y_s_V_S_p_o_o_l_e_r_O_p_t_i_o_n_s_S_t_r_u_c_t structure.
  104.  
  105.      The _S_L_S_y_s_V_G_e_t_P_r_i_n_t_e_r_O_p_t_i_o_n_s and _S_L_S_y_s_V_S_a_v_e_P_r_i_n_t_e_r_O_p_t_i_o_n_s functions read
  106.      and write System V printer specific options, respectively.  These are
  107.      System V spooling system specific functions and an error indication will
  108.      be returned if these functions are called when the System V spooler is
  109.      not the current spooling system. Printer specific options are saved in
  110.      the directory /_v_a_r/_s_p_o_o_l/_l_p/_s_e_t_t_i_n_g_s/<_p_r_i_n_t_e_r _n_a_m_e>.  Each user's option
  111.      file will be named by username. A default option file named
  112.      _d_e_f_a_u_l_t_S_e_t_t_i_n_g_s may be found in the printer settings directory and, if it
  113.      exists, will be used if no user option file is found. The printer
  114.      specific options file consists of a single line of options. The contents
  115.      are all the options specified using the ----oooo command line switch to the _l_p
  116.      command. Printer specific options cannot be saved for printer classes.
  117.  
  118.      _p_r_i_n_t_e_r        specifies the name of the printer for which options are to
  119.                     be read or written.  If NNNNUUUULLLLLLLL, the default printer will be
  120.                     used.
  121.  
  122.      _s_e_t_t_i_n_g_s_p      is set by the _S_L_G_e_t_P_r_i_n_t_e_r_S_e_t_t_i_n_g_s function to point to an
  123.                     _S_L_S_e_t_t_i_n_g_s_S_t_r_u_c_t structure containing the job and printer
  124.                     settings information. The contents of this structure must
  125.                     be copied to caller storage if they are to be preserved
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. SSSSLLLLGGGGeeeettttPPPPrrrriiiinnnntttteeeerrrrSSSSeeeettttttttiiiinnnnggggssss((((3333))))          IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo           SSSSLLLLGGGGeeeettttPPPPrrrriiiinnnntttteeeerrrrSSSSeeeettttttttiiiinnnnggggssss((((3333))))
  137.  
  138.  
  139.  
  140.                     across subsequent calls to the _S_L_G_e_t_P_r_i_n_t_e_r_S_e_t_t_i_n_g_s
  141.                     function.  If spooler or printer options cannot be found
  142.                     or the specified printer does not exist, the default
  143.                     values specified below will be assigned to the
  144.                     _S_L_S_e_t_t_i_n_g_s_S_t_r_u_c_t structure fields.
  145.  
  146.      _s_p_o_o_l_e_r__o_p_t_s_p  is set by the _S_L_S_y_s_V_G_e_t_S_p_o_o_l_e_r_O_p_t_i_o_n_s function to point to
  147.                     an _S_L_S_y_s_V_S_p_o_o_l_e_r_O_p_t_i_o_n_s_S_t_r_u_c_t. This structure contains the
  148.                     System V spooler options.  The contents of this structure
  149.                     must be copied to caller storage if they are to be
  150.                     preserved across subsequent calls to the
  151.                     _S_L_S_y_s_V_G_e_t_S_p_o_o_l_e_r_O_p_t_i_o_n_s function.  If spooler options
  152.                     cannot be found, the default values specified below will
  153.                     be assigned to the _S_L_S_y_s_V_S_p_o_o_l_e_r_O_p_t_i_o_n_s_S_t_r_u_c_t structure
  154.                     fields.
  155.  
  156.      _s_p_o_o_l_e_r__o_p_t_s   specifies to the _S_L_S_y_s_V_S_a_v_e_S_p_o_o_l_e_r_O_p_t_i_o_n_s function the
  157.                     values of the spooler options to be saved. These values
  158.                     are passed in the _S_L_S_y_s_V_S_p_o_o_l_e_r_O_p_t_i_o_n_s_S_t_r_u_c_t structure.
  159.  
  160.      _p_r_i_n_t_e_r__o_p_t_s_p  is set by the _S_L_S_y_s_V_G_e_t_P_r_i_n_t_e_r_O_p_t_i_o_n_s function to point to
  161.                     a string containing the printer specific options. The
  162.                     options within the string are separated by whitespace. If
  163.                     no options are found for the specified printer or the
  164.                     printer does not exist, this pointer is set to NNNNUUUULLLLLLLL.
  165.  
  166.      _p_r_i_n_t_e_r__o_p_t_s   specifies to the _S_L_S_y_s_V_S_a_v_e_P_r_i_n_t_e_r_O_p_t_i_o_n_s function the
  167.                     string of printer specific options to be saved.
  168.  
  169.      _l_o_c_a_t_i_o_n       specifies to the _S_L_S_y_s_V_S_a_v_e_P_r_i_n_t_e_r_O_p_t_i_o_n_s function whether
  170.                     the options to be saved are only for the caller
  171.                     (SSSSLLLL____SSSSAAAAVVVVEEEE____UUUUSSSSEEEERRRR) or are for all users of the specified
  172.                     printer (SSSSLLLL____SSSSAAAAVVVVEEEE____DDDDEEEEFFFFAAAAUUUULLLLTTTT). Note that to save options for
  173.                     all users the caller must have the username _r_o_o_t or _l_p as
  174.                     determined from the effective user ID.
  175.  
  176.      The _S_L_S_e_t_t_i_n_g_s_S_t_r_u_c_t is defined as:
  177.  
  178.           typedef struct _slSettingsStruct {
  179.               int copy;      /* 1 == copy to spooling dir, 0 == link */
  180.               int mail;      /* 1 == send mail on completion         */
  181.               char *title;   /* Print job banner page title. If NULL */
  182.                              /*      the system default banner title */
  183.                              /*      is to be used.                  */
  184.               char *options; /* Spooling system specific options     */
  185.                              /*      (e.g. -w and -o under System V  */
  186.                              /*      and -h under BSD)               */
  187.           } SLSettingsStruct;
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. SSSSLLLLGGGGeeeettttPPPPrrrriiiinnnntttteeeerrrrSSSSeeeettttttttiiiinnnnggggssss((((3333))))          IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo           SSSSLLLLGGGGeeeettttPPPPrrrriiiinnnntttteeeerrrrSSSSeeeettttttttiiiinnnnggggssss((((3333))))
  203.  
  204.  
  205.  
  206.      The default values for the fields of the _S_L_S_e_t_t_i_n_g_s_S_t_r_u_c_t are spooling
  207.      system dependent and are listed in the following table.
  208.  
  209.                        Field     Sys V Default   BSD Default
  210.                        _____________________________________
  211.                        copy      0               1
  212.                        mail      0               0
  213.                        title     NULL            NULL
  214.                        options   NULL            NULL
  215.  
  216.      The _S_L_S_y_s_V_S_p_o_o_l_e_r_O_p_t_i_o_n_s_S_t_r_u_c_t is defined as:
  217.  
  218.           typedef struct _slSysVSpoolerOptionsStruct {
  219.               int copy;        /* 1 == copy to spooling dir, 0 == link */
  220.               int mail;        /* 1 == send mail on completion         */
  221.               int message;     /* 1 == send message on completion      */
  222.               int suppress_id; /* 1 == suppress job ID message         */
  223.               char *title;     /* Print job banner page title. If NULL */
  224.                                /*      the system default banner title */
  225.                                /*      is to be used.                  */
  226.           } SLSysVSpoolerOptionsStruct;
  227.  
  228.  
  229.      The default values for the fields of the _S_L_S_y_s_V_S_p_o_o_l_e_r_O_p_t_i_o_n_s_S_t_r_u_c_t are
  230.      listed in the following table.
  231.  
  232.                             Field         Sys V Default
  233.                             ___________________________
  234.                             copy          0
  235.                             mail          0
  236.                             message       0
  237.                             suppress_id   0
  238.                             title         NULL
  239.  
  240. RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEE
  241.      All functions return 0 if execution was successful. -1 is returned and
  242.      _S_L_e_r_r_n_o is set if an execution error has occurred.
  243.  
  244. EEEEXXXXEEEECCCCUUUUTTTTIIIIOOOONNNN EEEERRRRRRRROOOORRRR CCCCOOOODDDDEEEESSSS
  245.      All functions will fail under the following circumstances.
  246.  
  247.      SL_ERR_FIND_SPOOLER      An error occurred while attempting to determine
  248.                               the available printer spooling systems.
  249.  
  250.      SL_ERR_NO_SPOOLERS       There are no printer spooling systems available.
  251.  
  252.  
  253.      SL_ERR_NO_DEF_PRINTER    There is no default printer registered with the
  254.                               printer spooling system.
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. SSSSLLLLGGGGeeeettttPPPPrrrriiiinnnntttteeeerrrrSSSSeeeettttttttiiiinnnnggggssss((((3333))))          IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo           SSSSLLLLGGGGeeeettttPPPPrrrriiiinnnntttteeeerrrrSSSSeeeettttttttiiiinnnnggggssss((((3333))))
  269.  
  270.  
  271.  
  272.      SL_ERR_BAD_PRINTER_NAME  The printer name specified is either an empty
  273.                               string (""), or a string consisting entirely of
  274.                               whitespace.
  275.  
  276.      In addition, the _S_L_S_y_s_V... functions will fail under the following
  277.      circumstances.
  278.  
  279.      SL_ERR_NO_SYSV           This function requires that the System V spooler
  280.                               be the current spooling system.
  281.  
  282.      And the _S_L_S_y_s_V_S_a_v_e... functions can fail for the following reason.
  283.  
  284.      SL_ERR_SAVE_OPTIONS      The options file could not be saved. Check the
  285.                               value of errno.
  286.  
  287. WWWWAAAARRRRNNNNIIIINNNNGGGG
  288.      The pointers to _s_e_t_t_i_n_g_s_p, _s_p_o_o_l_e_r__o_p_t_s_p, and _p_r_i_n_t_e_r__o_p_t_s_p are invalid
  289.      across subsequent calls to their functions. The data pointed to must be
  290.      copied to be preserved.  Note that the character string fields of the
  291.      structures must be duplicated in any copy operation since these pointers
  292.      also become invalid.
  293.  
  294. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  295.      glp(1), lp(1), SLPerror(3), libspool(3)
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.                                                                         PPPPaaaaggggeeee 5555
  328.  
  329.  
  330.  
  331.